An API is an application programming interface. It is a set of rules and definitions that let programs communicate with each other. REST stands for representational state transfer; this describes the architectural style and rules according to which the API is built. The developer builds the API on the server, according to the REST rules, and lets the client talk to the API.
When you link to a specific URL, you'll get a piece of data. The URL is referred to as a request, while the data sent to you is referred to as a response.
From the Master Flow, you can use the REST API node to call a REST API and have the data returned to the node or injected into a variable.
REST API Properties
General
Display Name
The name of the REST API node. By default, the node will be called REST API 1, REST API 2, and so on. You can change the node name from this field.
Description
You can add a description to the node; this can be a useful way of documenting the node for yourself and other users.
Rest API
Method
Choose the required REST API method.
URL
Paste the relevant URL.
Note: If you are using a URL with an HTTPS (HTTP Secure) schema, you may need to add a certificate for the target address to Pyramid's list of certificates. Administrators can use the Admin Console's Certificate Manager to add a certificate. For more information, see Certificate Manager.
Expression
Select the Expression checkbox to enable the PQL editor. Where this option is selected, the PQL icon is shown in the URL field (green arrow, above). Click the icon to open the PQL editor, where you can write a PQL expression to make the URL dynamic rather than static.
- Click here to review documentation of the PQL Common functions.
- Click here to learn more about the PQL editor.
- Click here to learn about PQL syntax.
Authentication
Choose the required method of authentication.
Custom HTTP Request Fields
You can add HTTP request fields. For example, if you want to call an API that requires authorization, add Authorization to the request fields. Or if you want to return only json content, select Content-Type and then write 'json' in the Expression field. Configure complex expressions using variables by opening the Expression Editor.
Content
The Content window (green highlight below) is only shown when you select POST or PUT from the Method drop-down. Enter the content that you want to send to the URL. The content can be static or based on a PQL expression.
Select the Expression checkbox to enable the PQL editor, where you can build your dynamic content using PQL.
Set Variable Values
Reference a variable to have the API return a value to the variable; you may opt to have the HTTP status code returned, the content returned, or both. The values will be returned in the Current Value column of the given variable in the Variables panel.
Example
In this example, the REST API node is used to call a URL with a GET method. The Execute Process node is used to ping Google, and then load the result into a variable called PingResult:
Next, another variable called IpValue is loaded into the Set Variable node; its value is set to a PQL expression that returns the IP address of the URL that was pinged:
SubString(@PingResult,IndexOf(@PingResult, "[") + 1, IndexOf(@PingResult, "]"))
Next, the Rest API node is used to send a GET request to the given URL. The URL is made dynamic by adding PQL to it, to inject the value of the IpValue variable (previous step) into the URL:
"https://ipapi.co/"+ @IpValue+"/json/"
The content retrieved from the request is then loaded into the variable called ipInfo (orange arrow, below):
Next, an email is sent out with the results that were loaded into the ipInfo variable (the content returned by the GET request):
Once the flow is executed, we see the variable results:
- PingResult stores the value from the Execute Process node which was used to ping Google.
- IpValue was injected into the Set Variable node and stores the IP address of the URL that was pinged.
- ipInfo stores the content retrieved by the GET request.
